dot Env
HAWKI 2: Configuration environment varibales
HAWKI 2 is built with the Lavarel framework for PHP. This allows to configure the application by editing the *.php files in the config directory. However, by default these files are writtin in such a way that most settings can also be changed with environment variables. This is handy because changing the config files would mean to change the HAWKI 2 source code, since these files are managed in the HAWKI git repository and also contained in the installation packages. Environment variables, however, are set in the OS (or your hosting environment).
Additionaly, Lavarel reads the contents of a .env file in the project root directory to override the environment variables. This file is not contained in the HAWKI installation as it is meant for developers and administrators to set their local configuration values.
This file is a template for the .env file. It documents all relevant settings, their allowed values and their defaults. Simply copy this file (don't just rename it) to a new file called .env and change the values as needed. The pre-set values will provide a sensible configuration for a "localhost deployment" for developers. Commented out settings are not strictly needed and usually contain the default values found in the config/*.php files.
Important: the .env example file includes several unused variables which are left in the file only for future development plans or as guidelines for community developers (such as AWS, Redis, Pusher and many more attributes). These variables can be ignored or removed if you prefer so.
Global Application Settings
| Variable | Default Value | Description |
|---|---|---|
| APP_NAME | HAWKI | Application name, can be anything you like HAWKI |
| APP_ENV | local | Deployment type: "local", "statiging" or "production" |
| APP_URL | http://127.0.0.1:8000 or https://hawki.com | Public URL to access the web interface |
| APP_DEBUG | true | Enable debug output: "true" or "false" |
| APP_TIMEZONE | CET | Timezone of the web server |
| APP_LOCALE | de_DE | Default language of the user interface (de_DE, en_US) |
| APP_FALLBACK_LOCALE | de_DE | Fallback language (for any missing translations) |
| APP_FAKER_LOCALE | de_DE | You shouldn't need this |
| APP_KEY | base64:12345678= | Encryption key: 32 random characters (e.g. created with https://www.random.org/strings) |
| APP_PREVIOUS_KEYS | Comma seperated list of previously used encryption keys | |
| APP_MAINTENANCE_DRIVER | file | Maintenance mode driver: "cache" or "file": "cache" allows setting the maintenance mode across multiple machines |
| APP_MAINTENANCE_STORE | database | Maintenance mode storage: "database" or ??? |
Database server
HAWKI uses a database to save chats and other data. For this a relation SQL database like MariaDB (MySQL) or Postgres should be used in production. For local development SQlite provides a zero-config default solution (but note that SQlite is single-user only and stores all data in a single file).
IMPORTANT: When using a database other than SQlite set DB_DATABASE to a sensible value. Because the default value in config/database.php is "lavarel" which is less clear and could at least in theory already be in use by other applications.
| Variable | Default Value | Description |
|---|---|---|
| DB_CONNECTION | mysql | Database server type: "mysql", "sqlite", "mariadb", "pgsql", "sqlsrv" (see config/database.php) |
| DB_URL | Database connection URL (instead of host and port) | |
| DB_HOST | 127.0.0.1 | Database server host name |
| DB_PORT | 3306 | Database server port number |
| DB_SOCKET | Unix domain socket instead of URL, host and port (MySQL and MariaDB only) | |
| DB_DATABASE | Database name (please change!) | |
| DB_USERNAME | root | Username to access the database server |
| DB_PASSWORD | root | Password to access the database server |
| DB_CHARSET | utf8mb4 | Character encoding of the database |
| DB_COLLATION | utf8mb4_unicode_ci | Database collation (MySQL and MariaDB only) |
Filesystem Storage
Uploaded media files are typically stored on disk and served from an asset web server. However, to simplify the setup the uploaded files will be served by PHP by default, though thos is not so good for performance. Alternateively Amazon S3 could be used.
NOTE: If you want to serve media files with your web server, choose "public" for FILESYSTEM_DISK. In this case make the server serve the files from the "app/public" directory. The HTTP address must be your APP_URL followed by "/storage".
| Variable | Default Value | Description |
|---|---|---|
| FILESYSTEM_DISK | local | Storage type: "local", "public", "s3" (see config/filesystem.php) |
Session Configuration
These are essential Laravel default variables for session management and they must be present and active to ensure proper session handling within the application.
| Variable | Default Value | Description |
|---|---|---|
| SESSION_DRIVER | database | Specifies the session "driver" or handler used to store session data. Common choices include "file", "cookie", "database", etc. Typically, "database" is used if sessions are stored in the database. |
| SESSION_LIFETIME | 120 | The session lifetime in minutes. It determines how long a session remains active before it expires. |
| SESSION_ENCRYPT | false | Indicates whether session data should be encrypted. Accepts "true" or "false". When set to "true", it adds an extra layer of security by encrypting session data. |
| SESSION_PATH | / | Defines the path for which the session cookie is available. The default value is "/". |
| SESSION_DOMAIN | null | Specifies the domain that the session cookie is available to. Use "null" to default to the current domain. |
| SESSION_EXPIRE_ON_CLOSE | true | Defines whether the session should expire when the browser is closed. Set to "true" to expire sessions on browser close, enhancing session security. |
Event Broadcasting
Lavarel contains an internal mechanism to broadcast events amongst servers. Normaly you shouldn't need to change the settings here. Just use the values below and only change them if you really know what you are doing.
| Variable | Description |
|---|---|
| BROADCAST_CONNECTION | Broadcasting mechanism: "reverb" |
For websocket connectivity Lavarel provides a special server called Reverb. This must be set up for HAWKI since many features rely on real-time communication via web sockets.
| Variable | Default Value | Description |
|---|---|---|
| REVERB_HOST | 127.0.0.1 / hawki.com | Hostname of the Reverb server (set to your top-level domain for production) |
| REVERB_PORT | 8080 / 443 | Port number of the Reverb server (set to 443 for production) |
| REVERB_SERVER_HOST | 0.0.0.0 | Hostname of the Reverb server (set to 0.0.0.0 for production) |
| REVERB_SERVER_PORT | 8080 | Port number of the Reverb server (set to 8080 for production) |
| REVERB_SCHEME | http/https | Connection protocol for the Reverb server: "http" or "https" |
| REVERB_APP_ID | hawki | Reverb application Id, can be anything you like? |
| REVERB_APP_SECRET | 123456789 | Password to access the Reverb server??? |
| REVERB_APP_KEY | 123456789 | Secret key to access the Reverb server ??? |
| REVERB_APP_PING_INTERVAL | 60 | Ping interval in seconds ??? |
| REVERB_APP_MAX_MESSAGE_SIZE | 10000 | Maximum message size in bytes ??? |
| REVERB_SCALING_ENABLED | false | "true" or "false" |
| REVERB_SCALING_CHANNEL | reverb | "reverb" |
SSL Certificate Configuration
These environment variables are used to specify the SSL certificate and the corresponding private key that are essential for establishing secure TLS/SSL connections in certain broadcasting setups. This is particularly crucial when using Reverb or similar services with encrypted connections, ensuring data is securely transmitted over HTTPS.
| Variable | Description |
|---|---|
| SSL_CERTIFICATE | Specifies the path to your SSL certificate file. This certificate is used to authenticate and establish a secure connection between the server and the client. |
| SSL_CERTIFICATE_KEY | Specifies the path to the private key file corresponding to your SSL certificate. The key is required to confirm the identity of the server and encrypt the data being transmitted. |
In the broadcasting configuration, these variables are used to configure the Guzzle HTTP client with appropriate SSL settings. By providing these files, you enable SSL/TLS encryption for broadcast services, enhancing the security of data in transit.
Vite Environment Configuration
These Vite environment variables are used to configure the front-end build system and its integration with services such as Reverb for real-time functionality within the application.
| Variable | Description |
|---|---|
| VITE_APP_NAME | Represents the application's name used within the Vite build process. It is typically a direct reflection of the application's name set in the Laravel backend. |
| VITE_REVERB_APP_KEY | The Reverb application's key used for authentication. It should mirror the REVERB_APP_KEY variable set in the backend environment configuration. |
| VITE_REVERB_APP_CLUSTER | The cluster designation for the Reverb setup, which specifies which region or data center the real-time data will be managed through. |
| VITE_REVERB_HOST | Designates the host for the Reverb service. This is typically set from the corresponding backend environment variable REVERB_HOST. |
| VITE_REVERB_PORT | Specifies the port that the Reverb service will run on, consistent with the setup from the backend environment variable REVERB_PORT. |
| VITE_REVERB_SCHEME | Defines the protocol scheme used by the Reverb service, such as "http" or "https", typically mirroring the REVERB_SCHEME variable from the backend. |
Queue Worker Configuration
This configuration setting is used to specify the queue connection that should be used by the Laravel application. This is essential for managing asynchronous tasks such as sending emails, processing uploads, or any other task that can be handled in the background.
| Variable | Description |
|---|---|
| QUEUE_CONNECTION | Defines the queue connection that the Laravel application will use. Options include "sync", "database", "redis", etc. The "database" connection is typically used to store jobs in a database table, which is useful for tracking, retrying, or monitoring queued jobs effectively. |
Authentication and Authorization
Access to HAWKI is restricted for registered users. In a production environment, you usually want to connect to your LDAP directory, OpenID provider, or Shibboleth service to make HAWKI available to your staff and/or students. For simpler setups (e.g., a small project setup for a single course), you can use the built-in Test User Authentication mechanism. This allows defining a small set of pre-allocated users in the local database (set up in advance by you).
NOTE: If you want a small setup with fixed users but want to allow the users to change their passwords, you can install LLDAP (https://github.com/lldap/lldap) on the same machine than HAWKI.
Supported authentication methods:
- LDAP
- OIDC (OpenID Connect)
- Shibboleth
Set the AUTHENTICATION_METHOD variable to one of the following:
AUTHENTICATION_METHOD="LDAP"
AUTHENTICATION_METHOD="OIDC"
AUTHENTICATION_METHOD="Shibboleth"
According to your authentication method, set the necessary variables as follows:
LDAP Configuration
| Variable | Default Value | Description |
|---|---|---|
| LDAP_CONNECTION | Configure the LDAP connection. Currently only "default" is supported (see config/ldap.php) | |
| LDAP_HOST | "ldaps://...de" | Hostname of the LDAP server |
| LDAP_PORT | "636" | Port number of the LDAP server |
| LDAP_USERNAME | Distinguished Name (DN) used for bind operation | |
| LDAP_BIND_PW | "xxx" | Password to access the LDAP server |
| LDAP_BASE_DN | "xxx" | Base DN for the LDAP search |
| LDAP_TIMEOUT | Timeout for LDAP queries in seconds | |
| LDAP_SSL | Use SSL to connect to the LDAP server. Not recommended: "true" or "false" | |
| LDAP_TLS | Use TLS to connect to the LDAP server. Recommended: "true" or "false" | |
| LDAP_SASL | Use SASL to connect to the LDAP server: "true" or "false" | |
| LDAP_LOGGING | Enable logging of LDAP queries: "true" or "false" | |
| LDAP_CACHE | Enable caching of LDAP queries: "true" or "false" | |
| LDAP_ATTRIBUTES | cn,mail,employeetype,displayname | Attributes required for data extraction (Username, Email Address, Employee Type, Name) |
| LDAP_FILTER | "(|(sAMAccountName=username)(mail=username))" | Filter required for authentication based on Username |
| CACHE_DRIVER | Cache driver for caching LDAP queries: "file", ... | |
| TEST_USER_LOGIN | true / false | Reads the test users list in storage folder before LDAP. Set to true for allowing test access and add tester profile to the json file. |
Shibboleth Configuration
| Variable | Default Value | Description |
|---|---|---|
| SHIBBOLETH_LOGIN_URL | "Shibboleth.sso/Login?target=login.php" | Path to the Shibboleth login handler "{$scheme}://{$_SERVER['HTTP_HOST']}/{$loginPath}{$loginPage}" |
| SHIBBOLETH_LOGOUT_URL | URL for Shibboleth logout | |
| ShIBBOLETH_NAME_VAR | "displayname" | Defined attribute on shibboleth server for name |
| ShIBBOLETH_EMPLOYEETYPE_VAR | "email" | Defined attribute on shibboleth server for employee type |
| ShIBBOLETH_EMAIL_VAR | "employeetype" | Defined attribute on shibboleth server for email address |
OpenID Connect (OIDC) Configuration
| Variable | Default Value | Description |
|---|---|---|
| OIDC_IDP | "https://xxx" | URL of the OpenID Connect Identity Provider |
| OIDC_CLIENT_ID | "xxx" | Client ID for the OIDC application |
| OIDC_CLIENT_SECRET | "xxx" | Client secret for the OIDC application |
| OIDC_LOGOUT_URI | "xxx" | URI for OIDC logout |
| OIDC_SCOPES | profile,email | Scopes define the level of access that the client is requesting from the authorization server. |
| OIDC_FIRSTNAME_VAR | "firstname" | "firstname" |
| OIDC_LASTNAME_VAR | "lastname" | "lastname" |
| OIDC_EMAIL_VAR | "email" | "email" |
| OIDC_EMPLOYEETYPE_VAR | "employeetype" | "employeetype" |
External Communication Configuration
| Variable | Description |
|---|---|
| ALLOW_EXTERNAL_COMMUNICATION | This setting enables or disables the ability for users to generate and use API keys to access HAWKI models. When set to "true", users will be able to create API keys, allowing external applications to register and interact with HAWKI using the user's account. This is particularly useful for integrating HAWKI with third-party applications or for enabling programmatic access to HAWKI functionalities. Ensure that this feature is enabled only if you understand the security implications and have measures in place to protect API access and user data. |
Example: ALLOW_EXTERNAL_COMMUNICATION="true" or ALLOW_EXTERNAL_COMMUNICATION="false"
ALLOW_EXTERNAL_COMMUNICATION=false
Caching
The following settings allow use a dedicated cache server to speed up some often executed code paths like database queries and so on. Usually a very fast storage like Memcached or Redis is used for this. By default the local database will be used, which should be fine for most installations. So only change these values if you really need to.
| Variable | Description |
|---|---|
| CACHE_STORE | "array", "database", "file", "memcached", "redis", "dynamodb", "octane" (see config/cache.php) |
| CACHE_PREFIX | Prefix for cache keys (by default calculated from the app name) |
| DB_CACHE_TABLE | ??? |
| DB_CACHE_CONNECTION | ??? |
| DB_CACHE_LOCK_CONNECTION | ??? |
| MEMCACHED_HOST | ??? |
| MEMCACHED_PORT | ??? |
| MEMCACHED_USERNAME | ??? |
| MEMCACHED_PASSWORD | ??? |
| MEMCACHED_PERSISTENT_ID | ??? |
| REDIS_CACHE_CONNECTION | cache |
| REDIS_CACHE_LOCK_CONNECTION | default |
| DYNAMODB_CACHE_TABLE | ??? |
| DYNAMODB_ENDPOINT | ??? |
Email Configuration
The email configuration settings allow the application to send invitation emails to users, enabling them to invite other users to group chats. This feature is currently in beta testing. Ensure that the mail server settings are correctly configured to enable email functionality.
|MAIL_MAILER| smtp |The mailer method to use for sending emails. Typically set to "smtp".| |MAIL_HOST| smtp.email.com |The hostname of the SMTP server used to send emails.| |MAIL_PORT| 587 |The port number used by the SMTP server. Use 465 for SSL or 587 for TLS.| |MAIL_USERNAME| |The username for authenticating with the SMTP server.| |MAIL_PASSWORD| |The password for authenticating with the SMTP server.| |MAIL_ENCRYPTION| tls |The encryption method used to secure email transmissions. Use 'ssl' for port 465.| |MAIL_FROM_ADDRESS| our_gmail_address@email.com |The email address that will appear as the sender of the invitation emails.| |MAIL_FROM_NAME| "HAWKI" |The display name that will appear as the sender of the invitation emails.|
Encryption Configuration
For enhanced security, HAWKI utilizes individual salts for each component to ensure that data is encrypted uniquely. While not mandatory, using unique hash keys for each component is recommended to maximize the security of user data, invitations, AI components, passkeys, and backups.
| Variable | Description |
|---|---|
| USERDATA_ENCRYPTION_SALT | The salt used specifically for encrypting user data. |
| INVITATION_SALT | The salt used for encrypting invitations data. |
| AI_CRYPTO_SALT | Used to generate a derived key for the AI messages in the groupchat |
| PASSKEY_SALT | The salt used for encrypting passkey data, contributing to robust password and credential security. |
| BACKUP_SALT | The salt used to encrypt backup data, ensuring their security during storage and transfer. |
Links
| Variable | Description |
|---|---|
| IMPRINT_LOCATION | The URL to your organization imprint page. |